home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / Vk / VkMsgService.z / VkMsgService
Encoding:
Text File  |  2002-10-03  |  14.6 KB  |  331 lines
  1.  
  2.  
  3.  
  4. VVVVkkkkMMMMssssggggSSSSeeeerrrrvvvviiiicccceeee((((3333xxxx))))                                              VVVVkkkkMMMMssssggggSSSSeeeerrrrvvvviiiicccceeee((((3333xxxx))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      VkMsgService - ViewKit object-oriented interface to the ToolTalk message
  10.      service
  11.  
  12. IIIINNNNHHHHEEEERRRRIIIITTTTSSSS FFFFRRRROOOOMMMM
  13.      VkMsgFacility
  14.  
  15. HHHHEEEEAAAADDDDEEEERRRR FFFFIIIILLLLEEEE
  16.      #include <Vk/VkMsgService.h>
  17.  
  18. PPPPUUUUBBBBLLLLIIIICCCC PPPPRRRROOOOTTTTOOOOCCCCOOOOLLLL SSSSUUUUMMMMMMMMAAAARRRRYYYY
  19.    CCCCoooonnnnssssttttrrrruuuuccccttttoooorrrr////DDDDeeeessssttttrrrruuuuccccttttoooorrrr
  20.            VkMsgService(Widget w,
  21.                         const char* ptid = NULL,
  22.                         const char* sessid = NULL);
  23.  
  24.            void ~VkMsgService(void);
  25.  
  26.  
  27.    RRRReeeeggggiiiissssttttrrrryyyy
  28.            void registerPatterns(VkMsgClient* client, Widget w);
  29.  
  30.            void registerClient(VkMsgClient* client,
  31.                                VkMsgFacilityCallback callback,
  32.                                void* client_data);
  33.  
  34.            void unregisterClient(VkMsgClient* client);
  35.  
  36.            void updatePatterns(void);
  37.  
  38.            char* mangleTranslationName(char* name,
  39.                                        VkMsgClient* client,
  40.                                        Boolean useCounter);
  41.  
  42.  
  43.    SSSSeeeennnnddddiiiinnnngggg RRRReeeeqqqquuuueeeessssttttssss
  44.            VkMsgMessage sendRequest(VkMsgClient* client, char* op,
  45.                                    int argc, VkMsgArg* argv);
  46.  
  47.            VkMsgMessage sendRequest(VkMsgClient* client, char* op);
  48.  
  49.            VkMsgMessage sendRequest(VkMsgClient* client,
  50.                                     VkMsgMessage msg_out);
  51.  
  52.            VkMsgMessage sendFileRequest(VkMsgClient* client,
  53.                                         char* op, char* file,
  54.                                         int argc, VkMsgArg* argv);
  55.  
  56.            VkMsgMessage sendFileRequest(VkMsgClient* client,
  57.                                         char* op, char* file);
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. VVVVkkkkMMMMssssggggSSSSeeeerrrrvvvviiiicccceeee((((3333xxxx))))                                              VVVVkkkkMMMMssssggggSSSSeeeerrrrvvvviiiicccceeee((((3333xxxx))))
  71.  
  72.  
  73.  
  74.    MMMMeeeessssssssaaaaggggeeee AAAAccccttttiiiioooonnnnssss
  75.            VkMsgPattern addAction(char* op, char* action,
  76.                                   VkMsgActionType type,
  77.                                   VkMsgClient* client);
  78.  
  79.            VkMsgPattern createAction(char* op, char* action,
  80.                                      VkMsgActionType type,
  81.                                      VkMsgClient* client);
  82.  
  83.            void removeAction(VkMsgPattern pat);
  84.  
  85.            VkMsgServicePair* findAction(VkMsgPattern pat);
  86.  
  87.  
  88.  
  89.  
  90. XXXX RRRREEEESSSSOOOOUUUURRRRCCCCEEEESSSS AAAASSSSSSSSOOOOCCCCIIIIAAAATTTTEEEEDDDD WWWWIIIITTTTHHHH TTTTHHHHIIIISSSS CCCCLLLLAAAASSSSSSSS
  91.      vkmsgTranslations        String to automatically register message
  92.      patterns
  93.  
  94. CCCCLLLLAAAASSSSSSSS DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  95.      VkMsgService is a subclass of VkMsgFacility that adds object-level
  96.      dispatch rather than the process-level dispatch that the ToolTalk service
  97.      provides.  It keeps track of which clients (VkMsgClient) send which
  98.      messages, and routes the replies to the correct object.  It also manages
  99.      the different message actions corresponding to each client.
  100.  
  101.  
  102.  
  103. FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNN DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNNSSSS
  104.    VVVVkkkkMMMMssssggggSSSSeeeerrrrvvvviiiicccceeee(((())))
  105.            VkMsgService(Widget w,
  106.                         const char* ptid = NULL,
  107.                         const char* sessid = NULL);
  108.  
  109.            void ~VkMsgService(void);
  110.  
  111.  
  112.           The VkMsgFacility constructor opens a ToolTalk connection and sets
  113.           up its callback for received messages and replies.  The second
  114.           argument can be used to provide a ToolTalk process type (ptype).
  115.           The third argument specifies the ToolTalk session ID.  If "default,"
  116.           connects to the default ToolTalk session ID.  If "nodefault,"
  117.           creates a private ToolTalk session.
  118.  
  119.    rrrreeeeggggiiiisssstttteeeerrrrPPPPaaaatttttttteeeerrrrnnnnssss(((())))
  120.            void registerPatterns(VkMsgClient* client, Widget w);
  121.  
  122.  
  123.           Checks for a vkmsgTranslations resource value for the widget and if
  124.           found, registers the specified message patterns.  The client must
  125.           still register message actions.  This mechanism is not recommended.
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. VVVVkkkkMMMMssssggggSSSSeeeerrrrvvvviiiicccceeee((((3333xxxx))))                                              VVVVkkkkMMMMssssggggSSSSeeeerrrrvvvviiiicccceeee((((3333xxxx))))
  137.  
  138.  
  139.  
  140.    rrrreeeeggggiiiisssstttteeeerrrrCCCClllliiiieeeennnntttt(((())))
  141.            void registerClient(VkMsgClient* client,
  142.                                VkMsgFacilityCallback callback,
  143.                                void* client_data);
  144.  
  145.  
  146.           Adds a client.  The callback is called when this client receives a
  147.           message.
  148.  
  149.    uuuunnnnrrrreeeeggggiiiisssstttteeeerrrrCCCClllliiiieeeennnntttt(((())))
  150.            void unregisterClient(VkMsgClient* client);
  151.  
  152.  
  153.           Removes the client.  Patterns and actions must be removed by the
  154.           client.
  155.  
  156.    sssseeeennnnddddRRRReeeeqqqquuuueeeesssstttt(((())))
  157.            VkMsgMessage sendRequest(VkMsgClient* client,
  158.                                     char* op,
  159.                                     int argc, VkMsgArg* argv);
  160.  
  161.  
  162.           Send a request.  The first argument is the operator string, the
  163.           second argument is the number of message arguments, and the third
  164.           argument is the array of message arguments.  Returns the ToolTalk
  165.           message object for the request.
  166.  
  167.            VkMsgMessage sendRequest(VkMsgClient* client, char* op);
  168.  
  169.  
  170.           Send a request.  The first argument is the operator string, and the
  171.           composed message arguments list is used (see the composeBegin and
  172.           composeAdd methods).
  173.  
  174.            VkMsgMessage sendRequest(VkMsgClient* client,
  175.                                     VkMsgMessage msg_out);
  176.  
  177.  
  178.           Send a pre-formatted request.
  179.  
  180.    sssseeeennnnddddFFFFiiiilllleeeeRRRReeeeqqqquuuueeeesssstttt(((())))
  181.            VkMsgMessage sendFileRequest(VkMsgClient* client,
  182.                                         char* op, char* file,
  183.                                         int argc, VkMsgArg* argv);
  184.  
  185.  
  186.           Like the _s_e_n_d_R_e_q_u_e_s_t() method, but sets the filename attribute to
  187.           the second argument.
  188.  
  189.            VkMsgMessage sendFileRequest(VkMsgClient* client,
  190.                                         char* op, char* file);
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. VVVVkkkkMMMMssssggggSSSSeeeerrrrvvvviiiicccceeee((((3333xxxx))))                                              VVVVkkkkMMMMssssggggSSSSeeeerrrrvvvviiiicccceeee((((3333xxxx))))
  203.  
  204.  
  205.  
  206.           Like the _s_e_n_d_R_e_q_u_e_s_t() method, but sets the filename attribute to
  207.           the second argument.
  208.  
  209.    aaaaddddddddAAAAccccttttiiiioooonnnn(((())))
  210.            VkMsgPattern addAction(char* op, char* action,
  211.                                   VkMsgActionType type,
  212.                                   VkMsgClient* client);
  213.  
  214.  
  215.           Adds a message action.  The first argument is the message operator
  216.           string.  The second argument is the name of the action (this will
  217.           usually be the same as the message operator, but different if a
  218.           translation is used).  The third argument specifies the type of
  219.           action, _V_K__M_S_G__A_C_T_I_O_N__O_B_S_E_R_V_E (notices), _V_K__M_S_G__A_C_T_I_O_N__H_A_N_D_L_E
  220.           (requests), _V_K__M_S_G__A_C_T_I_O_N__H_A_N_D_L_E__S_P_E_C_I_F_I_C (requests matching the
  221.           exact pattern), _V_K__M_S_G__A_C_T_I_O_N__R_E_P_L_Y (replies to requests),
  222.           _V_K__M_S_G__A_C_T_I_O_N__F_A_I_L (failed requests), _V_K__M_S_G__A_C_T_I_O_N__S_T_A_R_T (autostart
  223.           of handlers to service requests).
  224.  
  225.           Be sure to add your message actions before entering any Xt event
  226.           loop.  Otherwise, messages may be received before the action is
  227.           registered, and they will not be processed as expected.  The Xt
  228.           event loop is entered when you call VkApp::run, or when you post a
  229.           ViewKit dialog and a short, secondary event loop is entered.
  230.  
  231.    ccccrrrreeeeaaaatttteeeeAAAAccccttttiiiioooonnnn(((())))
  232.            VkMsgPattern createAction(char* op, char* action,
  233.                                      VkMsgActionType type,
  234.                                      VkMsgClient* client);
  235.  
  236.  
  237.           Creates a message action, but doesn't register it yet.  You can then
  238.           use ToolTalk routines like _V_k_M_s_g_P_a_t_t_e_r_n_A_r_g() to add argument types
  239.           and values to the pattern before registering it with the
  240.           _r_e_g_i_s_t_e_r_P_a_t_t_e_r_n() method.  Use the _r_e_g_i_s_t_e_r_P_a_t_t_e_r_n() method to
  241.           register your pattern.
  242.  
  243.    rrrreeeemmmmoooovvvveeeeAAAAccccttttiiiioooonnnn(((())))
  244.            void removeAction(VkMsgPattern pat);
  245.  
  246.  
  247.           Removes an action.  The pattern is unregistered.
  248.  
  249.    ffffiiiinnnnddddAAAAccccttttiiiioooonnnn(((())))
  250.            VkMsgServicePair* findAction(VkMsgPattern pat);
  251.  
  252.  
  253.           Lookup the information associated with the message pattern.  This
  254.           information contains the message operator string, the action name,
  255.           the message reason for that action, the message pattern, and the
  256.           message client.
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. VVVVkkkkMMMMssssggggSSSSeeeerrrrvvvviiiicccceeee((((3333xxxx))))                                              VVVVkkkkMMMMssssggggSSSSeeeerrrrvvvviiiicccceeee((((3333xxxx))))
  269.  
  270.  
  271.  
  272.    uuuuppppddddaaaatttteeeePPPPaaaatttttttteeeerrrrnnnnssss(((())))
  273.            void updatePatterns(void);
  274.  
  275.  
  276.           Call updatePatterns when you want to add new message patterns after
  277.           connecting to the ToolTalk service.  To be safe, call this method
  278.           after you are done using the addAction and registerPattern methods.
  279.  
  280. IIIINNNNHHHHEEEERRRRIIIITTTTEEEEDDDD MMMMEEEEMMMMBBBBEEEERRRR FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNNSSSS
  281.    IIIInnnnhhhheeeerrrriiiitttteeeedddd ffffrrrroooommmm VVVVkkkkMMMMssssggggFFFFaaaacccciiiilllliiiittttyyyy
  282.           connect(), joinFile(), setCallback(), getPtype(), registerPattern(),
  283.           createPattern(), registerPattern(), unregisterPattern(),
  284.           destroyPattern(), sendNotice(), sendNotice(), sendStringNotice(),
  285.           sendIntNotice(), sendFileNotice(), sendFileNotice(),
  286.           sendStringFileNotice(), sendIntFileNotice(), sendRequest(),
  287.           sendRequest(), sendSyncRequest(), sendSyncRequest(),
  288.           sendFileRequest(), sendFileRequest(), sendSyncFileRequest(),
  289.           sendSyncFileRequest(), sendRequest(), composeBegin(), composeAdd(),
  290.           composeAdd(), composeAdd(), composeAdd(), composeList(),
  291.           composeNum(), sessionID(), sessionProperty(), setDefaultSession(),
  292.           computeSGISession(), startPrivateSession(), getCaseSession(),
  293.           getCaseProperty(), getDefaultSession(), breakOutOfEventLoop(),
  294.           findReplyWaitInfo(), newReplyWaitInfo(), popReplyWaitInfo(),
  295.           getRootProperty(), receiveReply(), connectToXt(), receiveMessage(),
  296.           callCallback(), makePathExplicit(), messageScope(), waitForReply(),
  297.           waitTimeOut(), receive_message(), receive_reply(), callback,
  298.           callbackData, msg, compose, composeSize, composeCount, sgi_session,
  299.           _sessionProperty, ptype, sessionId, numReplyWait, sizeReplyWait,
  300.           replyWaitInfo, firstConnect, selectionAtom
  301.  
  302.  
  303. CCCCLLLLAAAASSSSSSSSEEEESSSS UUUUSSSSEEEEDDDD BBBBYYYY TTTTHHHHIIIISSSS CCCCLLLLAAAASSSSSSSS
  304.      VkMsgClient, VkMsgFacility
  305.  
  306. KKKKNNNNOOOOWWWWNNNN CCCCLLLLAAAASSSSSSSSEEEESSSS TTTTHHHHAAAATTTT UUUUSSSSEEEE TTTTHHHHIIIISSSS CCCCLLLLAAAASSSSSSSS
  307.      VkMsgApp, VkMsgClient, VkMsgComponent, VkMsgService, VkMsgWindow
  308.  
  309. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  310.      VkMsgFacility, VkMsgApp, VkMsgClient, VkMsgComponent, VkMsgFacility,
  311.      VkMsgWindow
  312.      _V_i_e_w_K_i_t _P_r_o_g_r_a_m_m_e_r'_s _G_u_i_d_e
  313.      _T_h_e _X _W_i_n_d_o_w _S_y_s_t_e_m, DEC Press, Bob Sheifler and Jim Gettys
  314.      _T_h_e _X _W_i_n_d_o_w _S_y_s_t_e_m _T_o_o_l_k_i_t, DEC Press, Paul Asente and Ralph Swick
  315.      _T_h_e _O_S_F/_M_o_t_i_f _P_r_o_g_r_a_m_m_e_r_s _R_e_f_e_r_e_n_c_e, Prentice Hall, OSF
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.                                                                         PPPPaaaaggggeeee 5555
  328.  
  329.  
  330.  
  331.